Skip to content

docs: sync doc-review findings (2026-08-06) - #245

Merged
ysyneu merged 2 commits into
mainfrom
automation/doc-review-20260806-014513
Aug 6, 2026
Merged

docs: sync doc-review findings (2026-08-06)#245
ysyneu merged 2 commits into
mainfrom
automation/doc-review-20260806-014513

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Doc Review — 2026-08-06

Mode: diff (since 5 days ago)
Findings: 12 applied — 6 high, 3 medium, 3 low

Changes

Finding Type Module Doc Action
f001 missing_coverage ai-sre ai-sre/artifacts.mdx New 分享产物 section: 仅账户内 vs 公开链接 visibility, who may manage sharing, the anonymous CDN link shape, the content-snapshot model, 更新快照 / 撤销公开链接, and the 16 MiB cap
f002 config_drift ai-sre ai-sre/artifacts.mdx Publishable artifact types are no longer just HTML/Markdown — added a category/extension table (web, data, images, PDF, source, archives) and rewrote the frontmatter/overview framing
f003 config_drift ai-sre ai-sre/artifacts.mdx Card title truncates to one line with a hover tooltip (was documented as two lines); card type icon is now per-type, not HTML-vs-other
f004 missing_coverage ai-sre ai-sre/environments.mdx Added the 性能下降（degraded）Runner status: what it means, the two detection signals, automatic recovery, and that degraded Runners stay selectable in the environment picker
f005 config_drift ai-sre ai-sre/knowledge.mdx Knowledge-pack uploads validate by content (UTF-8 text, no NUL bytes), not by an extension allowlist; document conversion now covers only .pdf/.docx/.xlsx/.pptx/.html/.htm, with legacy .doc/.xls/.ppt rejected as binary
f006 feature_drift ai-sre ai-sre/sessions.mdx A subagent/A2A child session opened from a shared root is now viewable read-only through that link (no fork); the previous note said child sessions could not be shared at all
f007 missing_coverage ai-sre ai-sre/sessions.mdx Forking carries subagent/A2A dispatch chips and their child sessions into the new session, but copied dispatches always show as interrupted
f008 missing_coverage ai-sre ai-sre/sessions.mdx HTML/HTM are accepted chat attachments, read as plain text and rendered sandboxed
f009 stale_content ai-sre ai-sre/insight.mdx Entry kind renamed scheduled -> automation in two places, matching sessions.mdx
f010 missing_coverage rum rum/error-tracking/error-aggregation.mdx The Issue count on an application card deep-links into that application's error tracking list, scoped to the card's own window (last 24h, status all) with stale filters cleared
f011 missing_coverage monitors monitors/targets/servicemap.mdx (new) New ServiceMap page: how to open it, the resolution-status filter, hop range and focus mode, node and dependency detail fields, the unresolved-endpoint drawer with CSV export, the host list, and how to judge whether a topology is trustworthy
f012 missing_coverage monitors monitors/quickstart/quickstart.mdx The data source type picker lists only types that already have a configured data source, plus its loading/failed/empty states

All changes applied to both zh/ and en/ pages. The new ServiceMap page is registered in docs.json for both languages.

Validation

mint broken-links was run after the edits. It reported no issues in any file touched by this PR. (The entries it did list are all /zh/api-reference/* paths that come from a separate, in-flight API-reference regeneration in the same checkout — none of them are introduced or referenced by this branch.)

Review checklist

  • Verify field names, defaults and limits match current product behavior — especially the 16 MiB public-share cap, the degraded-status thresholds (3 consecutive timeouts, >20s each, 30-minute quiet recovery), and the ServiceMap query defaults (100 nodes / 200 edges) and confidence bucketing (>=0.85 high, >=0.5 medium)
  • Confirm the ServiceMap UI labels used in the new page match the console (both languages)
  • Check that feature descriptions accurately reflect user-facing behavior
  • Ensure tone and style match the rest of the docs
  • monitors/quickstart/quickstart.mdx 基础配置 screenshot may be stale — the rule-group picker became a read-only breadcrumb, which the image still shows as a picker. Not changed here; needs a human to look at the image.

Mapping warnings

None

Notes

  • f010 was retargeted from rum/quickstart/app-management.mdx (which has no application-card section) to rum/error-tracking/error-aggregation.mdx, where the Issue-list entry points are already described.

Follow-up commit — changelog + ServiceMap Beta marker

Added after the initial review pass, at the product owner's request:

File Change
zh/changelog/changelog.mdx, en/changelog/changelog.mdx New 2026-08-06 entry with two sections: artifact public links (snapshot semantics, update/revoke, 16 MiB cap, broadened publishable types) and ServiceMap (Beta)
zh/monitors/targets/servicemap.mdx, en/monitors/targets/servicemap.mdx Marked the page as Beta and stated the monit-agent eBPF dependency up front

The changelog entry links to /{zh,en}/monitors/targets/servicemap, which this same PR creates — so the entry and its target page land together and the links are never broken.

The matching website announcement is flashduty-website #43 (two entries, zh + en each). Its ServiceMap links point at the docs page added here, so this PR should merge first, or at the same time.

ysyneu added 2 commits August 6, 2026 02:19
@ysyneu
docs: sync doc-review findings (2026-08-06)
73a9152 
Covers product changes from the past five days across AI SRE, Monitors and RUM.

- ai-sre/artifacts: document public (anonymous) artifact sharing — account-only
  vs public-link visibility, the content-snapshot model, update/revoke, and the
  16 MiB cap; broaden publishable file types well beyond HTML/Markdown; correct
  the card type icon and title truncation
- ai-sre/environments: add the degraded Runner status, its two detection
  signals and recovery paths, and note that degraded Runners stay selectable
- ai-sre/knowledge: replace the extension allowlist with the content-based
  UTF-8 text rule; narrow the document-conversion list to the modern Office
  formats and call out legacy .doc/.xls/.ppt rejection
- ai-sre/sessions: subagent/A2A child sessions are viewable read-only through a
  shared root link (no fork); forked dispatches always show as interrupted;
  HTML attachments
- ai-sre/insight: entry kind scheduled -> automation, matching sessions.mdx
- monitors/targets: new ServiceMap page (topology canvas, node/dependency
  detail fields, unresolved endpoints, host list, evidence quality)
- monitors/quickstart: the data source type picker lists only configured types
- rum/error-tracking: the Issue count on an application card deep-links into
  the error tracking list with the card's own scope
@ysyneu
docs(changelog): announce public artifact links and ServiceMap (Beta)
c5371da 
- changelog: new 2026-08-06 entry covering the artifact public-link sharing
  mode (snapshot semantics, update/revoke, 16 MiB cap), the broadened set of
  publishable artifact types, and the ServiceMap topology feature
- monitors/targets/servicemap: mark the page as Beta and state the
  monit-agent eBPF dependency up front
@ysyneu
ysyneu merged commit d1f4ed7 into main Aug 6, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ysyneu